home *** CD-ROM | disk | FTP | other *** search
Text File | 1994-04-29 | 4.3 KB | 123 lines | [TEXT/R*ch] |
- /*
-
- Copyright: © Apple Computer, Inc. 1994
-
- author: Mike Engber
-
- AlarmPkgUtil - v6
-
- Version History
-
- v5
- - beta seeding release
- v6
- - first general release
- - fixed EnsureInternal bug that could cause -10401 errors
- - new icon
-
- v7
- - uses new alarm stub which fixes an obscure problem:
- If you remove a card containing the Calendar meeting
- with an alarm AND none of the internally stored meetings
- have alarms set - all alarms get cancelled.
- - detects old stub and allows you to replace it
- - handles case where alarm API is built-in to the ROM
- - does not report an error when it detects the SystemAlarmSoup,
- but the alarm stub not installed. This can happen if the user
- does a cold boot and then a restore (SystemAlarmSoup is restored,
- but not the stub)
-
- */
-
-
- Background
-
- The code for adding alarm functionality to a Newton is in the NTK
- platform file. It is automatically installed (if necessary) in a
- Newton whenever you use one of the following functions:
-
- kAddAlarmFunc
- kRemoveAlarmFunc
- kGetAlarmFunc
- kGetAppAlarmKeysFunc
- kRemoveAppAlarmsFunc
-
- It is installed in the internal user store of the Newton. (uses ~4K) This
- installation is permanent - until the user does a cold boot.
-
- This is a very serious matter. Your users need to be warned they may
- lose ~4K of internal storage if they use your app. Of course, this
- storage is not lost every time your app is run or for every different
- app that uses alarms. It is lost only once, when the alarm functionality
- is initially installed.
-
- On ROMs that have the alarm functionality built in - the installation is
- not necessary and will not take place. The current Message Pad ROMs do
- not have the alarm functionality built in.
-
- The alarm API is currently the only set of funcitons in the NTK platform
- file that does this type of permanent installation. Alarms are a special
- case. Many apps require the alarm functionality to persist in the Newton
- even if the app is not installed (e.g. on a card that has been removed).
- This means the code for the alarm API cannot simply reside in your app's
- package as is the case for the other APIs in the platform file.
-
-
-
- Intro
-
- AlarmPkgUtil is an app for programmers to use in testing their alarm
- code. It allows you to explictitly install/remove the alarm
- functionality into a Newton - something your users will be unable to
- do.
-
- You will want to use AlarmPkgUtil in order to test your app's robustness.
- E.g. test your app with the alarm functionality already installed, not
- previously installed, becoming installed while your app is already
- running, ...
-
- DO NOT DISTRIBUTE AlarmPkgUtil to your users. Allowing users to remove
- alarm functionality from the Newton will introduce all sorts of subtle
- problems you don't want to deal with - believe me.
-
-
- Usage
-
- The UI to AlarmPkgUtil should be self explanitory. There is only a single
- button that is labeled either "Install Alarm Package" or "Remove Alarm
- Package" whichever is appropriate.
-
- There is a status box below which tells you the current state of the
- system wrt the alarm functionality. If the state is *error*, the box
- will contain a list of items (each preceded by a + or -). This
- information will be useful to me in debugging any problems you
- encounter.
-
-
-
- Warnings
-
- -If you have the AlarmEnabler.pkg (from the first beta seed of the alarm
- API) installed or you have not reset since you removed it, then the
- AlarmPkgUtil may show an *error* state. Remove the AlarmEnabler.pkg and
- reset your Newton.
-
-
- -Alarm functionality may not be added to a Newton during an InstallScript
- or a RemoveScript. This means, if the alarm functionality is not already
- present in the Newton and you use one of the 5 alarm API functions - it
- may not succeed. (the Newton may hang in this situation - a reset will
- necessary)
-
- You can avoid this problem entirely by not using the alarm api during
- your install or remove scripts. Alternately, you can spawn deferred actions
- from your install/remove scripts to do your alarm related tasks.
-
-
- -It is important that you do not delete the alarm soup. If you do so, you
- will need to cold boot your Newton before AlarmPkgUtil will function
- properly. We are not documenting any details about the alarm soup - you
- should only interact with it through the alarm API functions.
- (Using AlarmPkgUtil to remove the alarm functionality does remove the
- alarm soup for you - safely)
-